Swagger interface (OpenAPI)
Note: Access to the Swagger JSON specifications does not require authentication, and to view the contents of the live UI. But to execute any API request (with a Try it out button) you will need to authenticate first using the Authorize button, as explained below. Note that the authentication is OAuth-based authentication using Planning Space user credentials, API key-based authentication does not grant access to the Swagger API resources.
OpenAPI, also known as Swagger, is a standard for creating specifications for REST-based APIs (see swagger.io, www.openapis.org). The Planning Space Web APIs use Swagger (version 2.0) to 'self-document' their API resources which means that you can access live information about the APIs in the form of either a JSON specification file, or a live help user interface.
Swagger specification JSON file
You can make API requests to each of the Planning Space module APIs as follows:
PlanningSpaceEconomics/swagger/v1/swagger.jsonPlanningSpaceFinancials/swagger/v1/swagger.jsonEconomicsCalculation/swagger/v1/swagger.jsonPlanningSpace/swagger/v1/swagger.jsonPlanningSpaceDataflow/swagger/v1/swagger.json(Dataflow API V1)PlanningSpaceDataflow/swagger/v2/swagger.json(Dataflow API V2)
The JSON files can be used with Swagger/OpenAPI tools that exist to work with Swagger specification files (version 2.0, the Web API Swagger files may not be compatible with OpenAPI 3.0 tools).
Swagger live help user interface
Important: The Swagger interface is a live connection to a Planning Space tenant. The content is generated live from the tenant's API server and it can take a few seconds to appear initially. When you execute an API request with a Try it out button you are sending the request to your live API server: GET requests will return the current data content of your tenant; API requests that modify data will make immediate and permanent changes to your Planning Space tenant.
You can use a browser to access the Swagger user interfaces as follows:
https://{SERVER_ADDRESS}/{TENANT}/PlanningSpace/swagger/index.html
https://{SERVER_ADDRESS}/{TENANT}/PlanningSpaceDataflow/swagger/index.html
https://{SERVER_ADDRESS}/{TENANT}/PlanningSpaceEconomics/swagger/index.html
https://{SERVER_ADDRESS}/{TENANT}/PlanningSpaceFinancials/swagger/index.html
https://{SERVER_ADDRESS}/{TENANT}/EconomicsCalculation/swagger/index.html
The Dataflow API has two versions (V1 and V2). In the live Swagger interface you can switch to different versions using the Select a spec dropdown selector at the top-right corner of the web page.
Authentication for 'Try it out'
In a Swagger UI, if you want to execute any API request with a Try it out button then you will need to perform prior authentication by clicking the Authorize button at the top of the page.
After clicking the button you will see a dialog Available authorizations: click the 'scopes' check box and then click the Authorize button in the dialog. At this point the OAuth server may detect that you have a recently-stored login token, or you may see the Planning Space interactive login screen where you need to enter your user credentials. Click the Close button to close the authorization dialog.
One authentication should remain valid for the duration of your session. If you need to logout, click the Authorize and click Logout in the dialog.
Note: When you execute an API request with a Try it out button you are sending the request to your live API server: GET requests will return the current data content of your tenant; API requests that modify data will make immediate and permanent changes to your Planning Space tenant.